<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Using Asio</title>
<link rel="stylesheet" href="../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../index.html" title="Asio">
<link rel="up" href="../index.html" title="Asio">
<link rel="prev" href="overview/implementation.html" title="Platform-Specific Implementation Notes">
<link rel="next" href="tutorial.html" title="Tutorial">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="asio C++ library" width="250" height="60" src="../asio.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="overview/implementation.html"><img src="../prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../home.png" alt="Home"></a><a accesskey="n" href="tutorial.html"><img src="../next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="asio.using"></a><a class="link" href="using.html" title="Using Asio">Using Asio</a>
</h2></div></div></div>
<h4>
<a name="asio.using.h0"></a>
      <span><a name="asio.using.supported_platforms"></a></span><a class="link" href="using.html#asio.using.supported_platforms">Supported
      Platforms</a>
    </h4>
<p>
      The following platform and compiler combinations are regularly tested:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
          Linux using g++ 4.1 or later
        </li>
<li class="listitem">
          Linux using clang 3.2 or later
        </li>
<li class="listitem">
          FreeBSD using g++ 4.1 or later
        </li>
<li class="listitem">
          macOS using Xcode 8 or later
        </li>
<li class="listitem">
          Win32 using Visual C++ 9.0 or later
        </li>
<li class="listitem">
          Win32 using g++ 4.1 or later (MinGW)
        </li>
<li class="listitem">
          Win64 using Visual C++ 9.0 or later
        </li>
</ul></div>
<p>
      The following platforms may also work:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
          AIX
        </li>
<li class="listitem">
          Android
        </li>
<li class="listitem">
          HP-UX
        </li>
<li class="listitem">
          iOS
        </li>
<li class="listitem">
          NetBSD
        </li>
<li class="listitem">
          OpenBSD
        </li>
<li class="listitem">
          QNX Neutrino
        </li>
<li class="listitem">
          Solaris
        </li>
<li class="listitem">
          Tru64
        </li>
<li class="listitem">
          Win32 using Cygwin. (<code class="computeroutput">__USE_W32_SOCKETS</code> must be defined.)
        </li>
</ul></div>
<h4>
<a name="asio.using.h1"></a>
      <span><a name="asio.using.dependencies"></a></span><a class="link" href="using.html#asio.using.dependencies">Dependencies</a>
    </h4>
<p>
      The following libraries must be available in order to link programs that use
      Asio:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
          Boost.Coroutine (optional) if you use <a class="link" href="reference/spawn.html" title="spawn"><code class="computeroutput">spawn()</code></a>
          to launch coroutines.
        </li>
<li class="listitem">
          Boost.Regex (optional) if you use any of the <a class="link" href="reference/read_until.html" title="read_until"><code class="computeroutput">read_until()</code></a>
          or <a class="link" href="reference/async_read_until.html" title="async_read_until"><code class="computeroutput">async_read_until()</code></a>
          overloads that take a <code class="computeroutput">boost::regex</code> parameter.
        </li>
<li class="listitem">
          <a href="http://www.openssl.org" target="_top">OpenSSL</a> (optional) if you use
          Asio's SSL support.
        </li>
</ul></div>
<p>
      Furthermore, some of the examples also require Boost.Date_Time or Boost.Serialization
      libraries.
    </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
        With MSVC or Borland C++ you may want to add <code class="computeroutput">-DBOOST_DATE_TIME_NO_LIB</code>
        and <code class="computeroutput">-DBOOST_REGEX_NO_LIB</code> to your project settings to disable
        autolinking of the Boost.Date_Time and Boost.Regex libraries respectively.
        Alternatively, you may choose to build these libraries and link to them.
      </p></td></tr>
</table></div>
<h4>
<a name="asio.using.h2"></a>
      <span><a name="asio.using.optional_separate_compilation"></a></span><a class="link" href="using.html#asio.using.optional_separate_compilation">Optional
      separate compilation</a>
    </h4>
<p>
      By default, Asio is a header-only library. However, some developers may prefer
      to build Asio using separately compiled source code. To do this, add <code class="computeroutput">#include
      &lt;asio/impl/src.hpp&gt;</code> to one (and only one) source file in a program,
      then build the program with <code class="computeroutput">ASIO_SEPARATE_COMPILATION</code> defined
      in the project/compiler settings. Alternatively, <code class="computeroutput">ASIO_DYN_LINK</code>
      may be defined to build a separately-compiled Asio as part of a shared library.
    </p>
<p>
      If using Asio's SSL support, you will also need to add <code class="computeroutput">#include &lt;asio/ssl/impl/src.hpp&gt;</code>.
    </p>
<h4>
<a name="asio.using.h3"></a>
      <span><a name="asio.using.building_the_tests_and_examples_on_linux_or_unix"></a></span><a class="link" href="using.html#asio.using.building_the_tests_and_examples_on_linux_or_unix">Building
      the tests and examples on Linux or UNIX</a>
    </h4>
<p>
      If the boost directory (e.g. the directory called <code class="computeroutput">boost_1_34_1</code>)
      is in the same directory as the asio source kit, then you may configure asio
      by simply going:
    </p>
<pre class="programlisting">./configure
</pre>
<p>
      in the root directory of the asio source kit. Note that configure will always
      use the most recent boost version it knows about (i.e. 1.34.1) in preference
      to earlier versions, if there is more than one version present.
    </p>
<p>
      If the boost directory is in some other location, then you need to specify
      this directory when running configure:
    </p>
<pre class="programlisting">./configure --with-boost=<span class="emphasis"><em>path_to_boost</em></span>
</pre>
<p>
      When specifying the boost directory in this way you should ensure that you
      use an absolute path.
    </p>
<p>
      To build the examples, simply run <code class="computeroutput">make</code> in the root directory of
      the asio source kit. To also build and run the unit tests, to confirm that
      asio is working correctly, run <code class="computeroutput">make check</code>.
    </p>
<h4>
<a name="asio.using.h4"></a>
      <span><a name="asio.using.building_the_tests_and_examples_with_msvc"></a></span><a class="link" href="using.html#asio.using.building_the_tests_and_examples_with_msvc">Building
      the tests and examples with MSVC</a>
    </h4>
<p>
      To build using the MSVC 9.0 (or later) command line compiler, perform the following
      steps in a Command Prompt window:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
          If you are using a version of boost other than 1.34.1, or if the boost
          directory (i.e. the directory called <code class="computeroutput">boost_1_34_1</code>) is not
          in the same directory as the asio source kit, then specify the location
          of boost by running a command similar to <code class="literal">set BOOSTDIR=<span class="emphasis"><em>path_to_boost</em></span></code>.
          Ensure that you specify an absolute path.
        </li>
<li class="listitem">
          Change to the asio <code class="computeroutput">src</code> directory.
        </li>
<li class="listitem">
          Execute the command <code class="computeroutput">nmake -f Makefile.msc</code>.
        </li>
<li class="listitem">
          Execute the command <code class="computeroutput">nmake -f Makefile.msc check</code> to run a suite
          of tests to confirm that asio is working correctly.
        </li>
</ul></div>
<h4>
<a name="asio.using.h5"></a>
      <span><a name="asio.using.building_the_tests_and_examples_with_mingw"></a></span><a class="link" href="using.html#asio.using.building_the_tests_and_examples_with_mingw">Building
      the tests and examples with MinGW</a>
    </h4>
<p>
      To build using the MinGW g++ compiler from the command line, perform the following
      steps in a Command Prompt window:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
          If you are using a version of boost other than 1.34.1, or if the boost
          directory (i.e. the directory called <code class="computeroutput">boost_1_34_1</code>) is not
          in the same directory as the asio source kit, then specify the location
          of boost by running a command similar to <code class="literal">set BOOSTDIR=<span class="emphasis"><em>path_to_boost</em></span></code>.
          Ensure that you specify an absolute path using <span class="emphasis"><em>forward slashes</em></span>
          (i.e. <code class="computeroutput">c:/projects/boost_1_34_1</code> rather than <code class="computeroutput">c:\projects\boost_1_34_1</code>).
        </li>
<li class="listitem">
          Change to the asio <code class="computeroutput">src</code> directory.
        </li>
<li class="listitem">
          Execute the command <code class="computeroutput">make -f Makefile.mgw</code>.
        </li>
<li class="listitem">
          Execute the command <code class="computeroutput">make -f Makefile.mgw check</code> to run a suite
          of tests to confirm that asio is working correctly.
        </li>
</ul></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
        The above instructions do not work when building inside MSYS. If you want
        to build using MSYS, you should use <code class="literal">export</code> rather than
        <code class="literal">set</code> to specify the location of boost.
      </p></td></tr>
</table></div>
<h4>
<a name="asio.using.h6"></a>
      <span><a name="asio.using.macros"></a></span><a class="link" href="using.html#asio.using.macros">Macros</a>
    </h4>
<p>
      The macros listed in the table below may be used to control the behaviour of
      Asio.
    </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
              <p>
                Macro
              </p>
            </th>
<th>
              <p>
                Description
              </p>
            </th>
</tr></thead>
<tbody>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_ENABLE_BUFFER_DEBUGGING</code>
              </p>
            </td>
<td>
              <p>
                Enables Asio's buffer debugging support, which can help identify
                when invalid buffers are used in read or write operations (e.g. if
                a std::string object being written is destroyed before the write
                operation completes).
              </p>
              <p>
                When using Microsoft Visual C++ 11.0 or later, this macro is defined
                automatically if the compiler's iterator debugging support is enabled,
                unless <code class="computeroutput">ASIO_DISABLE_BUFFER_DEBUGGING</code> has been defined.
              </p>
              <p>
                When using g++, this macro is defined automatically if standard library
                debugging is enabled (<code class="computeroutput">_GLIBCXX_DEBUG</code> is defined), unless
                <code class="computeroutput">ASIO_DISABLE_BUFFER_DEBUGGING</code> has been defined.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_DISABLE_BUFFER_DEBUGGING</code>
              </p>
            </td>
<td>
              <p>
                Explictly disables Asio's buffer debugging support.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_DISABLE_DEV_POLL</code>
              </p>
            </td>
<td>
              <p>
                Explicitly disables <code class="literal">/dev/poll</code> support on Solaris,
                forcing the use of a <code class="computeroutput">select</code>-based implementation.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_DISABLE_EPOLL</code>
              </p>
            </td>
<td>
              <p>
                Explicitly disables <code class="computeroutput">epoll</code> support on Linux, forcing
                the use of a <code class="computeroutput">select</code>-based implementation.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_DISABLE_EVENTFD</code>
              </p>
            </td>
<td>
              <p>
                Explicitly disables <code class="computeroutput">eventfd</code> support on Linux, forcing
                the use of a pipe to interrupt blocked epoll/select system calls.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_DISABLE_KQUEUE</code>
              </p>
            </td>
<td>
              <p>
                Explicitly disables <code class="computeroutput">kqueue</code> support on macOS and BSD
                variants, forcing the use of a <code class="computeroutput">select</code>-based implementation.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_DISABLE_IOCP</code>
              </p>
            </td>
<td>
              <p>
                Explicitly disables I/O completion ports support on Windows, forcing
                the use of a <code class="computeroutput">select</code>-based implementation.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_DISABLE_THREADS</code>
              </p>
            </td>
<td>
              <p>
                Explicitly disables Asio's threading support, independent of whether
                or not Boost supports threads.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_NO_WIN32_LEAN_AND_MEAN</code>
              </p>
            </td>
<td>
              <p>
                By default, Asio will automatically define <code class="computeroutput">WIN32_LEAN_AND_MEAN</code>
                when compiling for Windows, to minimise the number of Windows SDK
                header files and features that are included. The presence of <code class="computeroutput">ASIO_NO_WIN32_LEAN_AND_MEAN</code>
                prevents <code class="computeroutput">WIN32_LEAN_AND_MEAN</code> from being defined.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_NO_NOMINMAX</code>
              </p>
            </td>
<td>
              <p>
                By default, Asio will automatically define <code class="computeroutput">NOMINMAX</code>
                when compiling for Windows, to suppress the definition of the <code class="computeroutput">min()</code>
                and <code class="computeroutput">max()</code> macros. The presence of <code class="computeroutput">ASIO_NO_NOMINMAX</code>
                prevents <code class="computeroutput">NOMINMAX</code> from being defined.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_NO_DEFAULT_LINKED_LIBS</code>
              </p>
            </td>
<td>
              <p>
                When compiling for Windows using Microsoft Visual C++ or Borland
                C++, Asio will automatically link in the necessary Windows SDK libraries
                for sockets support (i.e. <code class="literal">ws2_32.lib</code> and <code class="literal">mswsock.lib</code>,
                or <code class="literal">ws2.lib</code> when building for Windows CE). The
                <code class="computeroutput">ASIO_NO_DEFAULT_LINKED_LIBS</code> macro prevents these libraries
                from being linked.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_ENABLE_CANCELIO</code>
              </p>
            </td>
<td>
              <p>
                Enables use of the <code class="computeroutput">CancelIo</code> function on older versions
                of Windows. If not enabled, calls to <code class="computeroutput">cancel()</code> on a socket
                object will always fail with <code class="computeroutput">asio::error::operation_not_supported</code>
                when run on Windows XP, Windows Server 2003, and earlier versions
                of Windows. When running on Windows Vista, Windows Server 2008, and
                later, the <code class="computeroutput">CancelIoEx</code> function is always used.
              </p>
              <p>
                The <code class="computeroutput">CancelIo</code> function has two issues that should be
                considered before enabling its use:
              </p>
              <p>
                * It will only cancel asynchronous operations that were initiated
                in the current thread.
              </p>
              <p>
                * It can appear to complete without error, but the request to cancel
                the unfinished operations may be silently ignored by the operating
                system. Whether it works or not seems to depend on the drivers that
                are installed.
              </p>
              <p>
                For portable cancellation, consider using one of the following alternatives:
              </p>
              <p>
                * Disable asio's I/O completion port backend by defining ASIO_DISABLE_IOCP.
              </p>
              <p>
                * Use the socket object's close() function to simultaneously cancel
                the outstanding operations and close the socket.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_NO_TYPEID</code>
              </p>
            </td>
<td>
              <p>
                Disables uses of the <code class="computeroutput">typeid</code> operator in asio. Defined
                automatically if <code class="computeroutput">BOOST_NO_TYPEID</code> is defined.
              </p>
            </td>
</tr>
<tr>
<td>
              <p>
                <code class="computeroutput">ASIO_HASH_MAP_BUCKETS</code>
              </p>
            </td>
<td>
              <p>
                Determines the number of buckets in asio's internal <code class="computeroutput">hash_map</code>
                objects. The value should be a comma separated list of prime numbers,
                in ascending order. The <code class="computeroutput">hash_map</code> implementation will
                automatically increase the number of buckets as the number of elements
                in the map increases.
              </p>
              <p>
                Some examples:
              </p>
              <p>
                * Defining <code class="computeroutput">ASIO_HASH_MAP_BUCKETS</code> to <code class="computeroutput">1021</code>
                means that the <code class="computeroutput">hash_map</code> objects will always contain
                1021 buckets, irrespective of the number of elements in the map.
              </p>
              <p>
                * Defining <code class="computeroutput">ASIO_HASH_MAP_BUCKETS</code> to <code class="computeroutput">53,389,1543</code>
                means that the <code class="computeroutput">hash_map</code> objects will initially contain
                53 buckets. The number of buckets will be increased to 389 and then
                1543 as elements are added to the map.
              </p>
            </td>
</tr>
</tbody>
</table></div>
<h4>
<a name="asio.using.h7"></a>
      <span><a name="asio.using.mailing_list"></a></span><a class="link" href="using.html#asio.using.mailing_list">Mailing
      List</a>
    </h4>
<p>
      A mailing list specifically for Asio may be found on <a href="http://sourceforge.net/mail/?group_id=122478" target="_top">SourceForge.net</a>.
      Newsgroup access is provided via <a href="http://dir.gmane.org/gmane.comp.lib.boost.asio.user" target="_top">Gmane</a>.
    </p>
<h4>
<a name="asio.using.h8"></a>
      <span><a name="asio.using.wiki"></a></span><a class="link" href="using.html#asio.using.wiki">Wiki</a>
    </h4>
<p>
      Users are encouraged to share examples, tips and FAQs on the Asio wiki, which
      is located at <a href="http://think-async.com/Asio/" target="_top">http://think-async.com/Asio/</a>.
    </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M.
      Kohlhoff<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="overview/implementation.html"><img src="../prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../home.png" alt="Home"></a><a accesskey="n" href="tutorial.html"><img src="../next.png" alt="Next"></a>
</div>
</body>
</html>
